<HTML><HEAD><TITLE>session_sql_prepare(++Session, +ParamTemplate, ++SQL, -Cursor)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>session_sql_prepare(++Session, +ParamTemplate, ++SQL, -Cursor)</H1>
Prepares a SQL statement for execution by the DBMS.
<DL>
<DT><EM>Session</EM></DT>
<DD>A session handle
</DD>
<DT><EM>ParamTemplate</EM></DT>
<DD>Template defining the types of the parameters (structure or [])
</DD>
<DT><EM>SQL</EM></DT>
<DD>A SQL statement in prepared syntax (string)
</DD>
<DT><EM>Cursor</EM></DT>
<DD>Returned cursor handle
</DD>
</DL>
<H2>Description</H2>
<P>
 Prepares a SQL statement for execution. The statement is not actually
 executed, and a cursor_*_execute family of predicate is required to
 execute the predicate. This facility is only available if the DBMS
 supports prepared statements, and the SQL statement has to be written in
 the prepared statement syntax of the DBMS. The predicate returns the
 cursor handle representing this prepared statement in Cursor, which can
 then be used in subsequent library predicates.
</P><P>
 A prepared SQL statement is parsed by the DBMS, so that it could be
 executed more efficiently. It can also be parameterised, where the 
 parameters represent values to be filled in when the statement is
 executed. The statement can be executed multiple times with different
 parameters. The types of the parameters is specified by ParamTemplate,
 which is a Prolog structure of arity M (where M is the number of
 parameters for the statement), or the nil atom [] if there are no parameters.
 See the general description of this library or the manual for a
 description of the template specification.
 </P><P>
 The SQL statement must be valid for the DBMS to execute. It can contain
 NULL characters, i.e. it can contain binary data. The SQL statement cannot
 return any results. If it does, then an error would be raised when the SQL
 statement is actually executed. 
</P><P>
 Note that some DBMS restricts which SQL statements can be prepared. If an
 SQL statement cannot be prepared, it can still be executed using
 session_sql/3. 
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Session is not a valid session handle, or SQL not a string, or ParamTemplate not a structure
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while preparing SQL
<DT><EM>(dbi_bad_template) </EM>
<DD>ParamTemplate has the wrong arity
</DL>
<H2>Examples</H2>
<PRE>
  % note '?' in SQL in the syntax MySQL uses for placeholders. This may be
  % different in other DBMS
  transfer_(Session, Amount, FromAccount, ToAccount) :-
      SQL = "update accounts set balance = balance + ? \
                                               where id = ?",
      Deduct is - Amount,
      % incbal(1.0,12) is the parameter template
      session_sql_prepare(Session,incbal(1.0,12),SQL,1,Update),
      cursor_next_execute(Update,incbal(Deduct,FromAccount)),
      cursor_next_execute(Update,incbal(Amount,ToAccount)).</PRE>
<H2>See Also</H2>
<A HREF="../../lib/dbi/cursor_next_execute-2.html">cursor_next_execute / 2</A>, <A HREF="../../lib/dbi/cursor_all_execute-2.html">cursor_all_execute / 2</A>, <A HREF="../../lib/dbi/cursor_N_execute-4.html">cursor_N_execute / 4</A>, <A HREF="../../lib/dbi/cursor_close-1.html">cursor_close / 1</A>, <A HREF="../../lib/dbi/session_sql-3.html">session_sql / 3</A>, <A HREF="../../lib/dbi/session_sql_prepare_query-5.html">session_sql_prepare_query / 5</A>
</BODY></HTML>
